
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Media limitations of test devices &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Connections" href="connections.html" />
    <link rel="prev" title="QEMU options" href="qemu_options.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/secondary-media.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Media limitations of test devices</a><ul>
<li><a class="reference internal" href="#primary-media-and-primary-bootloaders">Primary media and primary bootloaders</a></li>
<li><a class="reference internal" href="#secondary-media">Secondary media</a><ul>
<li><a class="reference internal" href="#bootloader-limitations">Bootloader limitations</a></li>
<li><a class="reference internal" href="#occasional-debugging">Occasional debugging</a></li>
<li><a class="reference internal" href="#installer-testing">Installer testing</a><ul>
<li><a class="reference internal" href="#limitations">Limitations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#secondary-media-deployment-of-images">Secondary media deployment of images</a><ul>
<li><a class="reference internal" href="#id2">Limitations</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#principles-and-requirements">Principles and Requirements</a><ul>
<li><a class="reference internal" href="#test-writer-steps">Test Writer steps</a></li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
<li><a class="reference internal" href="#deploy-commands">Deploy commands</a></li>
<li><a class="reference internal" href="#boot-commands">Boot commands</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="qemu_options.html" title="Previous Chapter: QEMU options"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; QEMU options</span>
    </a>
  </li>
  <li>
    <a href="connections.html" title="Next Chapter: Connections"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Connections &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="media-limitations-of-test-devices">
<h1>Media limitations of test devices<a class="headerlink" href="#media-limitations-of-test-devices" title="Permalink to this heading">¶</a></h1>
<section id="primary-media-and-primary-bootloaders">
<span id="primary-media"></span><span id="index-0"></span><h2>Primary media and primary bootloaders<a class="headerlink" href="#primary-media-and-primary-bootloaders" title="Permalink to this heading">¶</a></h2>
<p>Methods like <a class="reference internal" href="actions-deploy.html#deploy-to-tftp"><span class="std std-ref">deploy to TFTP</span></a> rely on LAVA interrupting
the primary bootloader on the <a class="reference internal" href="glossary.html#term-DUT"><span class="xref std std-term">DUT</span></a> and changing the boot process to use
the files provided by the test writer. Many test devices require this
bootloader to be installed onto re-writeable media which can be modified from
the running system, for example an SD card.</p>
<p>The critical element for LAVA is the <strong>first point where the boot can
be interrupted or modified</strong>. Devices which lack some kind of
<a class="reference internal" href="glossary.html#term-BMC"><span class="xref std std-term">BMC</span></a> rely on this bootloader to be able to automatically
recover from a broken deployment. This bootloader can be considered as
the <strong>primary bootloader</strong> and the medium where this is installed can
be considered as the <strong>primary medium</strong> which <strong>must</strong> be protected
from deployments which would replace its entire contents. For example,
a panda board has an SD card and USB host support, the primary
bootloader (U-Boot) <strong>must</strong> be on the SD card, so V2 uses the SD card
as primary media. It is therefore not supportable for a panda board to
deploy to the SD card in LAVA.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Primary and secondary media relate to devices where the primary
bootloader is installed on writeable media and where that bootloader needs
to operate before new software can be deployed. Fastboot devices often
differ and allow all media on the device to be modified in test jobs as long
as jumpers or dip switches are set to force the device to boot into fastboot
mode. Modifying the fastboot support on the device may involve changing
those jumpers and/or dip switches, i.e. an admin task whilst the device is
offline.</p>
</div>
<p>It is important to consider the constraints of primary media as a limitation of
the hardware for automation. The risks of allowing test writers to easily brick
devices outweigh the usefulness of the primary media for files other than the
primary bootloader. LAVA has tried to use partitions on the primary media in
the past and this has proven to be unreliable.</p>
<p>Devices which only provide primary media can still support deployment methods
like TFTP to use ramdisk and NFS test jobs.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Many devices allow test writers to access the primary media from
within a test shell even if the test job has deployed into a ramdisk, NFS or
secondary media. It remains the responsibility of the test writer to <strong>not</strong>
modify the primary media from within a test shell <em>just because you can</em>.
Test writers who do so may have submission privileges revoked by the admins.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="review-criteria.html#essential-components"><span class="std std-ref">Only protect the essential components</span></a></p>
</div>
</section>
<section id="secondary-media">
<span id="index-1"></span><span id="id1"></span><h2>Secondary media<a class="headerlink" href="#secondary-media" title="Permalink to this heading">¶</a></h2>
<p>If the device supports any media other than <a class="reference internal" href="#primary-media"><span class="std std-ref">primary media</span></a>, all these media are collectively termed <strong>secondary media</strong>.
Any deployment to the secondary media can write a complete image including
partition tables and complete filesystems without affecting the ability of LAVA
to recover from a broken test job.</p>
<p>For example, a beaglebone-black can have a USB stick as secondary media. A
cubietruck can have a single SATA drive. A mustang device can have several SATA
drives attached. Usually, USB is the least useful secondary media as it is so
slow to write and the test job will be trying to write a full size filesystem
image of many gigabytes.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#primary-media"><span class="std std-ref">Primary media and primary bootloaders</span></a> and <a class="reference internal" href="admin-secondary-media.html#admin-secondary-media"><span class="std std-ref">Enabling Secondary Media</span></a></p>
</div>
<section id="bootloader-limitations">
<h3>Bootloader limitations<a class="headerlink" href="#bootloader-limitations" title="Permalink to this heading">¶</a></h3>
<p>The bootloader may be unable to write to permanent media. Usually this is a
good thing, bootloaders which can write to media can be problematic, slow
and/or greedy of resources on the worker e.g. fastboot, necessitating the use
of LXC. U-Boot and Grub are each restricted to reading files from media and not
writing new files during the boot process. To deploy a test image to the
secondary media, the device needs to first boot into a full OS environment with
threading, multiple cores, network and full kernel support. A standard test
shell can then write to the media in various ways. Depending on the device
configuration, test writers may still need to respect the location of the
primary bootloader to avoid bricking the device.</p>
<p>LAVA can use secondary media in a number of different ways, depending on the
use case.</p>
</section>
<section id="occasional-debugging">
<span id="secondary-media-commands"></span><span id="index-2"></span><h3>Occasional debugging<a class="headerlink" href="#occasional-debugging" title="Permalink to this heading">¶</a></h3>
<p>Combined with a <a class="reference internal" href="hacking-session.html#hacking-session"><span class="std std-ref">hacking session</span></a>, the boot commands can
be overridden to test support on selected devices. The primary bootloader will
still be used, for example to read files from the filesystem. Optionally, the
kernel can be loaded over TFTP to use the filesystem on the secondary media as
a form of persistence.</p>
<p><a class="reference external" href="https://playground.validation.linaro.org/scheduler/job/80647/definition">https://playground.validation.linaro.org/scheduler/job/80647/definition</a></p>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Unless the device is restricted to particular submitters <strong>and</strong>
any health check has been disabled, the next test job could replace, corrupt
or update the root filesystem on the secondary media. The full process would
have to be reset.</p>
</div>
</section>
<section id="installer-testing">
<span id="secondary-media-installer"></span><span id="index-3"></span><h3>Installer testing<a class="headerlink" href="#installer-testing" title="Permalink to this heading">¶</a></h3>
<p>An operating system installer is the traditional form of secondary media
deployments. The installer boots into a ramdisk to allow complete access to the
device, including all media. The installer can be used to do the deployment to
the secondary media in LAVA, although support will be required to automate the
questions and prompts normally raised during the process.</p>
<p>This method has the advantage that the final system is a fresh, clean install
and the disadvantage that the whole system has to be recreated each test job,
as well as the overhead of starting and running the installer.</p>
<section id="limitations">
<h4>Limitations<a class="headerlink" href="#limitations" title="Permalink to this heading">¶</a></h4>
<ul class="simple">
<li><p><strong>Installer may try to write new UEFI or new UBoot</strong> - the automation of the
installer will need to prevent overwriting the primary bootloader. (If your
test job bricks the device, the admin could revoke or suspend your submission
rights.)</p></li>
<li><p><strong>Not advised for most UBoot devices</strong> - many installer programs need special
support to install onto UBoot devices and it could be hard to both update the
kernel in the installed system and prevent modification of the primary
bootloader.</p></li>
<li><p><strong>Chainload installed Grub from the primary Grub bootloader</strong> -  Writing a
second bootloader to the secondary media can work, as long as the second
bootloader can be chainloaded from the primary bootloader by issuing commands
to the primary bootloader.</p></li>
<li><p><strong>Wait for the installer to run</strong></p>
<ul>
<li><p>Large SATA drives can take long time to partition.</p></li>
<li><p>Downloads from mirrors may take time to install</p></li>
</ul>
</li>
</ul>
</section>
</section>
<section id="secondary-media-deployment-of-images">
<span id="secondary-media-images"></span><span id="index-4"></span><h3>Secondary media deployment of images<a class="headerlink" href="#secondary-media-deployment-of-images" title="Permalink to this heading">¶</a></h3>
<p>Secondary media deployments are a way of automating the deployment of a
filesystem image directly to the secondary media. The image will need to
contain the partition(s) and filesystem(s) for the test system.</p>
<p>Unlike the installer support, secondary media deployments can work with
UBoot devices although many ARMv7 devices are limited by slow media like
USB drives instead of SATA.</p>
<section id="id2">
<h4>Limitations<a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h4>
<ul class="simple">
<li><p><strong>Make sure all tools are installed</strong> - The test job will download and apply
the image after completing a test shell, ensure <code class="docutils literal notranslate"><span class="pre">wget</span></code> is installed.</p></li>
<li><p><strong>New image may include new UEFI or new UBoot</strong> - The image to be deployed
will need to avoid overwriting the primary bootloader. (If your test job
bricks the device, the admin could revoke or suspend your submission rights.)</p></li>
<li><p><strong>Production images can be a risk</strong> - LAVA still needs to interrupt the
primary bootloader and add files to the deployed image to be able to run test
shell definitions. Production images often include security settings which
will disable this access, causing your tests to fail.</p></li>
<li><p><strong>Single write operation</strong> - LAVA downloads the image and then simply writes
the data to the media before rebooting. The image must be fully configured to
work in this way, including raising usable network interfaces directly upon
boot.</p></li>
</ul>
</section>
</section>
</section>
<section id="principles-and-requirements">
<h2>Principles and Requirements<a class="headerlink" href="#principles-and-requirements" title="Permalink to this heading">¶</a></h2>
<p>Secondary deployments are done by the device under test, using actions defined
by LAVA and tools provided by the initial deployment. Test writers need to
ensure that the initial deployment has enough support to complete the second
deployment.</p>
<p>Images on remote servers are downloaded to the dispatcher (and decompressed
where relevant) so that the device does not need to do the decompression or
need lots of storage in the initial deployment.</p>
<p>By keeping the downloaded image intact, it becomes possible to put the LAVA
extensions alongside the image instead of inside.</p>
<p>To make this work, several requirements must be met:</p>
<ul class="simple">
<li><p>The initial deployment must provide or support installation of all tools
necessary to complete the second deployment - it is a TestError if there is
insufficient space or the deployment cannot complete this step.</p></li>
<li><p>The initial deployment does not need enough space for the decompressed image,
however, the initial deployment is responsible for writing the decompressed
image to the secondary media from <code class="docutils literal notranslate"><span class="pre">stdin</span></code>, so the amount of memory taken up
by the initial deployment can have an impact on the speed or success of the
write.</p></li>
<li><p>The operation of the second deployment is an action which <strong>precedes</strong> the
second boot. There is no provision for getting data back from this test shell
into the boot arguments for the next boot. Any data which is genuinely
persistent needs to be specified in advance.</p></li>
<li><p>LAVA manages the path to which the second deployment is written, based on the
media supported by the device and the ID of that media. Where a device
supports multiple options for secondary media, the job specifies which media
is to be used.</p></li>
<li><p>LAVA will need to support instructions in the job definition which determine
whether a failed test shell should allow or skip the boot action following.</p></li>
<li><p>LAVA will declare available media using the <strong>kernel interface</strong> as the
label. A SATA drive which can only be attached to devices of a particular
<a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> using USB is still a USB device as it is constrained by
the USB interface being present in the test image kernel. A SATA drive
attached to a SATA connector on the board is a SATA device in LAVA
(irrespective of how the board actually delivers the SATA interface on that
connector).</p></li>
<li><p>If a device has multiple media of the same type, it is up to the test writer
to determine how to ensure that the correct image is booted. The <code class="docutils literal notranslate"><span class="pre">blkid</span></code> of
a partition within an image is a permanent UUID within that image and needs
to be determined in advance if this is to be used in arguments to the
bootloader as the root filesystem.</p></li>
<li><p>The manufacturer ID and serial number of the hardware to be used for the
secondary deployment must be set in the device configuration. This makes it
possible for test images to use such support as is available (e.g. <code class="docutils literal notranslate"><span class="pre">udev</span></code>)
to boot the correct device.</p></li>
<li><p>The job definition needs to specify which hardware to use for the second
deployment - if this label is based on a device node, it is a TestError if
the use of this label does not result in a successful boot.</p></li>
<li><p>The job definition also needs to specify the path to the kernel, dtb and the
partition containing the rootfs within the deployed image.</p></li>
<li><p>The job definition needs to include the bootloader commands, although
defaults can be provided in some cases.</p></li>
</ul>
<section id="test-writer-steps">
<h3>Test Writer steps<a class="headerlink" href="#test-writer-steps" title="Permalink to this heading">¶</a></h3>
<ul class="simple">
<li><p>always ensure you have set a usable root password in the image / test media
or set the root user to not have a password.</p>
<ul>
<li><p>If a password is set for the root user, the password <strong>must</strong> be declared
in the test job submission.</p></li>
</ul>
</li>
<li><p>always ensure you have set the bootable flag on the boot partition when
building the image.</p></li>
<li><p>always ensure you have installed a kernel into the image</p>
<ul>
<li><p>note down the paths to the kernel and initramfs etc. These will need to
be specified in the test job submission.</p></li>
</ul>
</li>
<li><p>always ensure you have the UUID of the new filesystem containing the root
filesystem. This will need to be specified in the test job submission.</p></li>
<li><p>ensure that if a bootloader is present in the image to be deployed that this
bootloader can be chainloaded by the primary bootloader already on the
device.</p></li>
</ul>
</section>
<section id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this heading">¶</a></h3>
<section id="deploy-commands">
<h4>Deploy commands<a class="headerlink" href="#deploy-commands" title="Permalink to this heading">¶</a></h4>
<p>This is an example block - the actual data values here are known not to work as
the <code class="docutils literal notranslate"><span class="pre">deploy</span></code> step is for a panda but the <code class="docutils literal notranslate"><span class="pre">boot</span></code> step in the next example
comes from a working cubietruck job.</p>
<p>This example uses a device configuration where <code class="docutils literal notranslate"><span class="pre">UUID-required</span></code> is True.</p>
<p>For simplicity, this example also omits the initial deployment and boot, at the
start of this block, the device is already running a kernel with a ramdisk or
rootfs which provides enough support to complete this second deployment.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># secondary media - use the first deploy to get to a system which can deploy the next</span>
<span class="c1"># in testing, assumed to already be deployed</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
<span class="w">    </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usb</span>
<span class="w">    </span><span class="c1"># not a real job, just used for unit tests</span>
<span class="w">    </span><span class="nt">compression</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gz</span>
<span class="w">    </span><span class="nt">image</span><span class="p">:</span>
<span class="w">      </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.gz</span>
<span class="w">    </span><span class="nt">device</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SanDisk_Ultra</span><span class="w"> </span><span class="c1"># needs to be exposed in the device-specific UI</span>
<span class="w">    </span><span class="nt">download</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/usr/bin/wget</span>
</pre></div>
</div>
<ol class="arabic simple">
<li><p>Ensure that the <code class="docutils literal notranslate"><span class="pre">deploy</span></code> action has sufficient time to download the
<strong>decompressed</strong> image <strong>and</strong> write that image directly to the media using
STDOUT. In the example, the deploy timeout has been set to ten minutes - in
a test on the panda, the actual time required to write the specified image
to a USB device was around 6 minutes.</p></li>
<li><p>Note the deployment strategy - <code class="docutils literal notranslate"><span class="pre">to:</span> <span class="pre">usb</span></code>. This is a direct mapping to the
kernel interface used to deploy and boot this image. The bootloader must
also support reading files over this interface.</p></li>
<li><p>The compression method used by the specified image is explicitly set.</p></li>
<li><p>The image is downloaded and decompressed by the dispatcher, then made
available to the device to retrieve and write to the specified media.</p></li>
<li><p>The device is specified as a label so that the correct UUID can be
constructed from the device configuration data.</p></li>
<li><p>The download tool is specified as a full path which must exist inside the
currently deployed system. This tool will be used to retrieve the
decompressed image from the dispatcher and pass STDOUT to the writer tool,
<code class="docutils literal notranslate"><span class="pre">dd</span></code> by default. If the download tool is the default <code class="docutils literal notranslate"><span class="pre">/usr/bin/wget</span></code>,
LAVA will add the following options:
<code class="docutils literal notranslate"><span class="pre">--no-check-certificate</span> <span class="pre">--no-proxy</span> <span class="pre">--connect-timeout=30</span> <span class="pre">-S</span>
<span class="pre">--progress=dot:giga</span> <span class="pre">-O</span> <span class="pre">-</span></code> If different download tools are required for
particular images, these can be specified, however, if those tools require
options, the test writer can either ensure that a script exists in the image
which wraps those options or file a bug to have the alternative tool options
supported.</p></li>
</ol>
<p>The default writer tool is <code class="docutils literal notranslate"><span class="pre">dd</span></code> but it is possible to specify an alternative
one.  In particular, <code class="docutils literal notranslate"><span class="pre">bmaptool</span></code> is usually a much better choice for USB or SD
card devices.  It will typically flash the image faster and extend the lifetime
of the storage media.  It needs a <code class="docutils literal notranslate"><span class="pre">.bmap</span></code> file which contains a block map
alongside the actual image file.  For this reason, two files need to be
downloaded and stored in the same directory on the dispatcher.  The example
below illustrates how to do this:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># secondary media deployment using bmaptool</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
<span class="w">    </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usb</span>
<span class="w">    </span><span class="c1"># not a real job, just used for illustrative purposes</span>
<span class="w">    </span><span class="nt">compression</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gz</span>
<span class="w">    </span><span class="nt">images</span><span class="p">:</span>
<span class="w">      </span><span class="nt">image</span><span class="p">:</span>
<span class="w">        </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.gz</span>
<span class="w">      </span><span class="nt">bmap</span><span class="p">:</span>
<span class="w">        </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.bmap</span>
<span class="w">    </span><span class="nt">uniquify</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w">    </span><span class="nt">device</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SanDisk_Ultra</span><span class="w"> </span><span class="c1"># needs to be exposed in the device-specific UI</span>
<span class="w">    </span><span class="nt">writer</span><span class="p">:</span>
<span class="w">      </span><span class="nt">tool</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/usr/bin/bmaptool</span>
<span class="w">      </span><span class="nt">options</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">copy {DOWNLOAD_URL} {DEVICE}</span>
<span class="w">      </span><span class="nt">prompt</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;bmaptool:</span><span class="nv"> </span><span class="s">info&#39;</span>
<span class="w">    </span><span class="nt">tool</span><span class="p">:</span>
<span class="w">      </span><span class="nt">prompts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&#39;copying</span><span class="nv"> </span><span class="s">time:</span><span class="nv"> </span><span class="s">[0-9ms\.\</span><span class="nv"> </span><span class="s">]+,</span><span class="nv"> </span><span class="s">copying</span><span class="nv"> </span><span class="s">speed</span><span class="nv"> </span><span class="s">[0-9\.]+</span><span class="nv"> </span><span class="s">MiB\/sec&#39;</span><span class="p p-Indicator">]</span>
</pre></div>
</div>
<ol class="arabic simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">images</span></code> list needs to contain one <code class="docutils literal notranslate"><span class="pre">image</span></code> entry and can have others
as well such as <code class="docutils literal notranslate"><span class="pre">bmap</span></code> in this case.  They will all be downloaded
separately to the dispatcher and made available to the board via HTTP.  The
URL of the <code class="docutils literal notranslate"><span class="pre">image</span></code> file is available in the job definition as
<code class="docutils literal notranslate"><span class="pre">{DOWNLOAD_URL}</span></code>.  The URL of the other images will need to be determined
by other means.  Say, the <code class="docutils literal notranslate"><span class="pre">image</span></code> file could be a manifest with the list
of the actual binary images (not the case with this <code class="docutils literal notranslate"><span class="pre">bmaptool</span></code> example).</p></li>
<li><p>Each item in the <code class="docutils literal notranslate"><span class="pre">images</span></code> list is normally downloaded into a separate
sub-directory such as <code class="docutils literal notranslate"><span class="pre">image</span></code> or <code class="docutils literal notranslate"><span class="pre">bmap</span></code> in this example.  As the
<code class="docutils literal notranslate"><span class="pre">bmaptool</span></code> expects both files to be in the same path, the <code class="docutils literal notranslate"><span class="pre">uniquify:</span>
<span class="pre">false</span></code> option is used so all the files are downloaded directly at the root
of the job’s <code class="docutils literal notranslate"><span class="pre">storage-deploy-*</span></code> directory.  Please note that if several
image files have the same name, they will overwrite each other when
<code class="docutils literal notranslate"><span class="pre">uniquify</span></code> is set to <code class="docutils literal notranslate"><span class="pre">false</span></code>.  For this reason, if not specified in the
job it will be set to <code class="docutils literal notranslate"><span class="pre">true</span></code> by default.</p></li>
<li><p>To use an alternative writer tool, the <code class="docutils literal notranslate"><span class="pre">writer</span></code> parameters are used.  The
absolute path to the tool must be provided with <code class="docutils literal notranslate"><span class="pre">tool</span></code> as well as the
<code class="docutils literal notranslate"><span class="pre">options</span></code> required to call it.  The <code class="docutils literal notranslate"><span class="pre">prompt</span></code> is used to detect that the
flashing has started.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">writer</span></code> tool will normally also be responsible for downloading the
image file, hence the <code class="docutils literal notranslate"><span class="pre">{DOWNLOAD_URL}</span></code> option passed to it in the example.
It is also possible to provide both <code class="docutils literal notranslate"><span class="pre">download</span></code> and <code class="docutils literal notranslate"><span class="pre">writer</span></code> parameters,
in which case the standard output of the downloader tool will be piped into
the standard input of the writer tool.</p></li>
<li><p>The tool <code class="docutils literal notranslate"><span class="pre">prompts</span></code> parameter is to detect when the writer tool has
completed the flashing operation.  When LAVA has matched a prompt with the
tool output, it will then proceed with the secondary boot action.  The
<code class="docutils literal notranslate"><span class="pre">prompts</span></code> parameters defaults are to match the output of <code class="docutils literal notranslate"><span class="pre">dd</span></code>, so they
should be defined appropriately when using an alternative writer tool.</p></li>
</ol>
<p>The kernel inside the initial deployment <strong>MUST</strong> support UUID when deployed on
a device where UUID is required, as it is this kernel which needs to make
<code class="docutils literal notranslate"><span class="pre">/dev/disk/by-id/$path</span></code> exist for <code class="docutils literal notranslate"><span class="pre">dd</span></code> to use. Remember not to quote the
UUID:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">root_uuid</span><span class="p">:</span> <span class="n">UUID</span><span class="o">=</span><span class="mi">159</span><span class="n">d17cc</span><span class="o">-</span><span class="mi">697</span><span class="n">c</span><span class="o">-</span><span class="mi">4125</span><span class="o">-</span><span class="mi">95</span><span class="n">a0</span><span class="o">-</span><span class="n">a3775e1deabe</span>
</pre></div>
</div>
</section>
<section id="boot-commands">
<h4>Boot commands<a class="headerlink" href="#boot-commands" title="Permalink to this heading">¶</a></h4>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
<span class="w">    </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">u-boot</span>
<span class="w">    </span><span class="nt">commands</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usb</span>
<span class="w">    </span><span class="nt">parameters</span><span class="p">:</span>
<span class="w">      </span><span class="nt">shutdown-message</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;reboot:</span><span class="nv"> </span><span class="s">Restarting</span><span class="nv"> </span><span class="s">system&quot;</span>
<span class="w">    </span><span class="c1"># these files are part of the image already deployed and are known to the test writer</span>
<span class="w">    </span><span class="nt">kernel</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/boot/vmlinuz-3.16.0-4-armmp-lpae</span>
<span class="w">    </span><span class="nt">ramdisk</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/boot/initrd.img-3.16.0-4-armmp-lpae.u-boot</span>
<span class="w">    </span><span class="nt">dtb</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/boot/dtb-3.16.0-4-armmp-lpae&#39;</span>
<span class="w">    </span><span class="nt">root_uuid</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UUID=159d17cc-697c-4125-95a0-a3775e1deabe</span><span class="w">  </span><span class="c1"># comes from the supplied image.</span>
<span class="w">    </span><span class="nt">boot_part</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span><span class="w">  </span><span class="c1"># the partition on the media from which the bootloader can read the kernel, ramdisk &amp; dtb</span>
<span class="w">    </span><span class="nt">prompts</span><span class="p">:</span>
<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;linaro-test&#39;</span>
<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;root@debian:~#&#39;</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">kernel</span></code> and (if specified) the <code class="docutils literal notranslate"><span class="pre">ramdisk</span></code> and <code class="docutils literal notranslate"><span class="pre">dtb</span></code> paths are the
paths used by the bootloader to load the files in order to boot the image
deployed onto the secondary media. These are <strong>not necessarily</strong> the same as
the paths to the same files as they would appear inside the image after
booting, depending on whether any boot partition is mounted at a particular
mountpoint.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">root_uuid</span></code> is the full option for the <code class="docutils literal notranslate"><span class="pre">root=</span></code> command to the kernel,
including the <code class="docutils literal notranslate"><span class="pre">UUID=</span></code> prefix.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">boot_part</span></code> is the number of the partition from which the bootloader can
read the files to boot the image. This will be combined with the device
configuration interface name and device_id to create the command to the
bootloader, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;setenv loadfdt &#39;load usb 0:1 $</span><span class="si">{fdt_addr_r}</span><span class="s2"> /boot/dtb-3.16.0-4-armmp-lpae&#39;&#39;&quot;</span><span class="p">,</span>
</pre></div>
</div>
<p>The dispatcher does NOT analyze the incoming image - internal UUIDs inside an
image do not change as the refactored dispatcher does <strong>not</strong> break up or
reorganize the partitions. Therefore, the UUIDs of partitions inside the image
<strong>MUST</strong> be declared by the job submissions.</p>
</section>
</section>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>